'\" t
.\"     Title: drm
.\"    Author: David Herrmann <dh.herrmann@googlemail.com>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: September 2012
.\"    Manual: Direct Rendering Manager
.\"    Source: libdrm
.\"  Language: English
.\"
.TH "DRM" "7" "September 2012" "libdrm" "Direct Rendering Manager"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
drm \- Direct Rendering Manager
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <xf86drm\&.h>
.fi
.ft
.SH "DESCRIPTION"
.PP
The
\fIDirect Rendering Manager\fR
(DRM) is a framework to manage
\fIGraphics Processing Units\fR
(GPUs)\&. It is designed to support the needs of complex graphics devices, usually containing programmable pipelines well suited to 3D graphics acceleration\&. Furthermore, it is responsible for memory management, interrupt handling and DMA to provide a uniform interface to applications\&.
.PP
In earlier days, the kernel framework was solely used to provide raw hardware access to privileged user\-space processes which implement all the hardware abstraction layers\&. But more and more tasks were moved into the kernel\&. All these interfaces are based on
\fBioctl\fR(2)
commands on the DRM character device\&. The
\fIlibdrm\fR
library provides wrappers for these system\-calls and many helpers to simplify the API\&.
.PP
When a GPU is detected, the DRM system loads a driver for the detected hardware type\&. Each connected GPU is then presented to user\-space via a character\-device that is usually available as
/dev/dri/card0
and can be accessed with
\fBopen\fR(2)
and
\fBclose\fR(2)\&. However, it still depends on the graphics driver which interfaces are available on these devices\&. If an interface is not available, the syscalls will fail with
EINVAL\&.
.SS "Authentication"
.PP
All DRM devices provide authentication mechanisms\&. Only a DRM\-Master is allowed to perform mode\-setting or modify core state and only one user can be DRM\-Master at a time\&. See
\fBdrmSetMaster\fR(3)
for information on how to become DRM\-Master and what the limitations are\&. Other DRM users can be authenticated to the DRM\-Master via
\fBdrmAuthMagic\fR(3)
so they can perform buffer allocations and rendering\&.
.SS "Mode\-Setting"
.PP
Managing connected monitors and displays and changing the current modes is called
\fIMode\-Setting\fR\&. This is restricted to the current DRM\-Master\&. Historically, this was implemented in user\-space, but new DRM drivers implement a kernel interface to perform mode\-setting called
\fIKernel Mode Setting\fR
(KMS)\&. If your hardware\-driver supports it, you can use the KMS API provided by DRM\&. This includes allocating framebuffers, selecting modes and managing CRTCs and encoders\&. See
\fBdrm-kms\fR(7)
for more\&.
.SS "Memory Management"
.PP
The most sophisticated tasks for GPUs today is managing memory objects\&. Textures, framebuffers, command\-buffers and all other kinds of commands for the GPU have to be stored in memory\&. The DRM driver takes care of managing all memory objects, flushing caches, synchronizing access and providing CPU access to GPU memory\&. All memory management is hardware driver dependent\&. However, two generic frameworks are available that are used by most DRM drivers\&. These are the
\fITranslation Table Manager\fR
(TTM) and the
\fIGraphics Execution Manager\fR
(GEM)\&. They provide generic APIs to create, destroy and access buffers from user\-space\&. However, there are still many differences between the drivers so driver\-depedent code is still needed\&. Many helpers are provided in
\fIlibgbm\fR
(Graphics Buffer Manager) from the
\fImesa\-project\fR\&. For more information on DRM memory\-management, see
\fBdrm-memory\fR(7)\&.
.SH "REPORTING BUGS"
.PP
Bugs in this manual should be reported to https://bugs\&.freedesktop\&.org/enter_bug\&.cgi?product=DRI&component=libdrm under the "DRI" product, component "libdrm"
.SH "SEE ALSO"
.PP
\fBdrm-kms\fR(7),
\fBdrm-memory\fR(7),
\fBdrmSetMaster\fR(3),
\fBdrmAuthMagic\fR(3),
\fBdrmAvailable\fR(3),
\fBdrmOpen\fR(3)
